Extended Help Overview

Extended Help leads the product user to information in the Rational Unified Process and other sources about how to perform tasks using the current tool. The other sources can be organization-specific, or project-specific standards and guidelines, or almost any other type of information that can be represented in a HTML document. The information accessed from Extended Help depends upon the context from which it is invoked. The context varies from task to task. For example, someone working on a use-case diagram in Rational Rose will be see different Extended Help information than someone working on a sequence diagram in the same product.

 Extended Help is driven by a set of databases that identify the context for each piece of information (called the target). One database is delivered with the Rational Unified Process and is registered upon installation. You may create and register any number of databases, each containing different information and pointers to different HTML pages. For example, you may have a database that contains pointers to pages that are appropriate for all projects in your organization. You may have another one that is specific to a project or project type. You might also decide to create a personal database with pointers to information that is important to you.

This document describes how to create and register your own Extended Help databases. It also provides the known contexts that you use to control information access.

 To create, populate and use your own Extended Help Database, follow the instructions below.

Creating Your Own Extended Help Database

Populating the Extended Help Database

Registering the Database and Translation Strings

Accessing the Database from Rational Tools

Table 1: Valid Product and Subtool Combinations

Creating Your Own Extended Help Database

To use a customized Extended Help database, you must:

• Populate the database with information
• Register the database and any string substitutions in the Windows Registry

There is a blank Extended Help database provided in the out-of-the-box folder (\common\OutOfTheBox) on your product CD. Follow the directions below to populate and use the database. After you have installed a Rational Suite or other procut on your machine, you can find the database in:"...Program Files\Rational\common\OutOfTheBox\customer databases\custinfo.mdb.

Populating the Extended Help Database

Copy custinfo.mdb to a location accessible by all product users. You will probably want to rename the database to identify the type of information contained there (e.g., companyinfo.mdb). You need Microsoft Access to populate the database. You do not need Access to use the database with Extended Help, only to populate it.

Open the database either through the Access File->Open or by double clicking on it.

Select the Forms tab and double click on the "Help information entry" form. The form will be displayed. You use this form to add, modify, or delete records from the database. Information on doing this can be found in the Microsoft Access documentation. If you are an experienced Microsoft Access user you may be more comfortable updating the table directly.

Enter information in the following six field to enable Extended Help to use the record:

product: This is the name of the Rational product from which a query is invoked. It must be one of the values specified in Table 1: Valid Product and Subtool combinations.

subtool: This is a specific context within the product. It must have one of the known values as shown in Table 1: Valid Product and Subtool combinations. There are different subtools possible for different products.

query: This is a category for the information pointed to by this entry. There are a set of known values, but you can use any value you wish. The name will be used as the name of a folder used to group like targets in the Extended Help browser. The maximum length of this field is 100 characters but this length is not recommended. An example of a query value is "Requirements Traceability" where targets for this query would identify the specific requirements traceability for the customer organization.

target: This field is a URL for the information supplied by this record for the specific product, subtool, and query. It may either be an absolute value or have translation strings embedded in it that will be replaced at run time. For example a target might be something like "<corpinfo>/requirements/traceability.html". The <corpinfo> translation string must be registered (described later). The maximum length of the target field is 255 characters.

short_description: This is the description that names the target under the appropriate folder in the Extended Help browser. The maximum length of this field is 50 characters.

description: This is a longer description that appears when the cursor is held over the item (tool tip data). The maximum length of this field is 255 characters.The following table shows the known values for the product and subtool fields and the legal combinations. The Extended Help Engine will only find records with a valid combination.NOTE: A value of "Any" used for the subtool indicates that any context within the product will match the record. You can also use "Any" for the Product field if you want the target to appear for all products.

Registering the Database and Translation Strings

Use regedit to update the registry to add the database (and any substitutions).

NOTE: You cannot use a translation string for the database itself; you must give it an absolute path.

Start regedit.

Open the folder: "HKEY_LOCAL_MACHINE\SOFTWARE\Rational Software\Rational Suite\1.0\Extended Help".
Select the folder you want to update, either databases or translations. The next set of steps assumes you want to update
the databases. Go to step 7 if you are modifying translation strings.

Click on the databases folder to see the names and values. You should see the default and RUPdb. Let's assume you
want to add your own database, MyDB and that it's located at D:\My Folders\MyDB.mdb.

Select Edit->New->String value. Enter a name for the string value, for example MyDB. The cursor should be positioned
in the selected string "New Value #1".

Right click on MyDB and select Modify.

In the dialog, enter the path to your database and click OK. Go to step 11.

If you are entering a translation string select the translations folder. You will see at least Default and "<rup>". Let's say
you have used "<dbroot>" as a substitution string in your database.

Select Edit->New->String value. Enter "<dbroot>" as the name.

Right click on "<dbroot>" and select Modify.

In the dialog, enter the value that should be substituted for "<dbroot>" when the records from the database are read.
Note the string will be used for all databases so you should make these values unique.

Exit regedit.

Accessing the Database from Rational Tools

Once you have created and registered a database you will be able to see your Extended Help database when you choose "Extended Help" from the Help menu in the tools for which you have defined context links.

Table 1. Valid Product and Subtool Combinations

Go to Top